DS-CD ROM 2 1993 August/DS CD-ROM 2.Ausgabe (August 1993).iso/programm/ds0045/mbmtexte.exe/SPRITLIB.DOC

Text File | 1992-03-24 | 21KB | 366 lines

Anleitung zur Sprite-Library für Turbo-Pascal 5.X  / 6.X in der Version 1.2

(C) 1991,92 BY UWE KUHRING

Kontakt: Uwe Kuhring
         Scheidter Str. 281
         6602 Dudweiler Saar
         Tel.: [phone]

         Postgiroamt Saarbrücken
         BLZ 590 100 66
         KNR 522 56 667
         Registrierungsgebühr siehe "PREISE.DOC"

****************************************************************************
* ACHTUNG - WICHTIGE ZUSATZINFORMATION                                     *
* Dies ist die SHARE-Version der Sprite-Library V1.2  (Teil d. MBM-Pakets) *
* Da ich Ihnen hierzu trotzdem die Original-Anleitung der Vollversion zur  *
* Durcharbeitung zur Verfügung stellen möchte, werde ich die Abweichungen  *
* zur registrierten Version hier kurz aufführen.                           *
* Der folgende Absatz zum Kopierverbot verliert seine Gültigkeit.          *
* Die Sprite-Library wurde nicht eingeschränkt. Sogar die Source-Codes der *
* Library sind in der Shareware-Version enthalten. Eine kommerzielle       *
* Nutzung, bzw. eine private Nutzung über den Erprobungszeitraum hinaus,   *
* setzt eine Registrierung voraus!                                         *
****************************************************************************

Zum Urheberrecht: Mit dem Erwerb dieser Vollversion 1.2 der Sprite-Library
steht Ihnen ein preisgünstiges Programm zur Erstellung und Verwendung von
mehrfarbigen Sprites in Turbo-Pascal zur Verfügung. Bitte beachten Sie aber,
daß es sich bei diesem Programm, obwohl es vielleicht der Preis und die
Mitlieferung der Sourcecodes erwarten lassen, nicht um Public-Domain,
sondern um Copyright-geschützte Software handelt. Sie dürfen die Routinen
benutzen, Ihren Erfordernissen anpassen und sie in Ihre Programme einbinden.
Diese Programme können Sie frei verkaufen, ohne daß Lizenzabgaben entstehen.
Untersagt bleibt jedoch die Weitergabe in unkompilierter Form (Source-Codes).
Auch wenn Sie sich entscheiden, bei Ihrem Produkt den Source-Code mit-
zuliefern, dürfen Sie die Source-Codes des MBM-Pakets nicht hinzufügen!
WICHTIG: Als Source-Code wird hier auch die .TPU Version der Library
verstanden! Obwohl diese ein Compilat darstellt, ist sie separat verwend-
bar und bildet so einen wesentlichen Teil dieses Programmpaketes. Nur Ihre
.EXE oder .COM Dateien dürfen die SPRITLIB.TPU beim Verkauf im Programmcode
enthalten!

Haftung: Ich übernehme keinerlei Haftung für Schäden, die durch die
Benutzung der Sprite-Library in irgendeiner Weise entstehen könnten.
Insbesondere gebe ich keine Garantie der Verwendbarkeit und Funktions-
fähigkeit der beschriebenen Prozeduren, auch wenn dieser Eindruck in der
folgenden Beschreibung der Software entstehen sollte.

Systemanforderungen:
1. Eine Maus samt Treiber ist unbedingt erforderlich.
2. Eine Grafikkarte aus der Gruppe HGC/CGA/MCGA/EGA/VGA.
3. Natürlich Turbo-Pascal und zwar ab Version 5.0
   (eventuell sind auch 4.X Versionen verwendbar, dies wurde nicht getestet)
4. DIE LIBRARY IST AUSSCHLIEßLICH IM GRAFIKMODUS EINSETZTBAR !


Es folgt eine Beschreibung der Programme.

Allgemeines zur Library und den Zusatzprogrammen

Die vier Programme dieses Paketes ermöglichen die Editierung beliebiger
farbiger Sprites. Zwölf Sprites gleichzeitig können in eigene Turbo-Pascal-
Programme mit der Hilfe der Library eingebunden werden. Die Handhabung der
Sprites wird mit nur 8 Prozeduren vollzogen. Dabei wird auch eine
Kollisionsbearbeitung angeboten.
Das mitgelieferte Demo-Programm wurde mit dieser Libraray erstellt.


Der Sprite-Editor (SPRITEED.EXE)

Um Sprites in eigenen Turbo-Pascal-Programmen einsetzen zu können, bedarf
es eines Werkzeuges, welches die Erstellung von Sprites ermöglicht.
Der Sprite-Editor erfüllt genau diese Funktion.
Nach dem Starten des Editors erscheint ein Menü, daß Ihnen verschiedene
Möglichkeiten der Sprite-Bearbeitung bietet. Sie wählen einen Menüpunkt an,
indem Sie auf der Tastatur die zugehörige Zahlentaste drücken.
Alle Manipulationen beziehen sich auf das aktuelle Sprite. Kurz nachdem
Sie den Editor gestartet haben, gibt es jedoch noch kein aktuelles Sprite.
Sie müssen erst eines erstellen. Es gibt zwei Möglichkeiten, ein aktuelles
Sprite zu erstellen:
1. Sie definieren ein neues Sprite mit der Taste <1>
   In diesem Fall erstellen Sie ein völlig neues Sprite. Falls es bereits
   ein altes Sprite im Speicher gab, wird dieses nach einer Sicherheitsab-
   frage gelöscht. Sie brauchen für das neue Sprite nur die Größe in X
   (horizontal) und die Größe in Y (vertikal) jeweils im Bereich von
   8 bis maximal 32 Pixeln anzugeben, danach ist dieses nun das aktuelle
   Sprite. Allerdings besteht das Sprite zur Zeit nur aus Leerzeilen.
   Die obige Beschränkung auf 8 bis 32 Pixel kann, bei der registrierten
   Vollversion, auch im Source-Code des Sprite-Editors verändert werden.
   Dies ist jedoch wenig sinnvoll, da erstens Sprites mit einer Größe von
   weniger als 8 Pixeln kaum etwas darstellen können und zweitens Sprites
   mit mehr als 32*32 Pixeln viel Rechenzeit zur Verschiebung brauchen.
   Letzteres Format bietet Ihnen immerhin schon 1024 Positionen im Sprite!
   Zwischen den Schranken ist jedes Format erlaubt, also auch 8*32, 32*8
   oder auch 29*13.
2. Sie laden ein altes Sprite mit der Taste <4> ein.
   Wählen Sie diesen Punkt an, so können Sie ein Sprite, welches Sie früher
   einmal erstellt haben, nochmals bearbeiten.
   Auch in diesem Fall wird ein eventuell vorhandenes altes Sprite im
   Speicher nach einer Sicherheitsabfrage gelöscht.

Egal, ob Sie sich für das Laden oder die Neudefinition eines Sprites
entschieden haben, nach diesem Vorgang kann dieses Sprite nun als aktuelles
Sprite im Editor bearbeitet werden.
Dazu muß die Taste <2> gedrückt werden. Sie gelangen dann in den eigentlichen
Editor, der vollständig mit der Maus bedient wird.
Es werden beide Tasten der Maus benutzt. Wenn Sie mit dem Mauszeiger auf ein
Karo in der Zeichenebene zeigen und die linke Maustaste drücken, so setzen
Sie dort die momentan eingestellte Vordergrundfarbe. Beim Druck auf die
rechte Maustaste wird das Feld hingegen mit der aktuellen Hintergrundfarbe
gefüllt. Die jeweils benutzte Vorder- bzw. Hintergrundfarbe können Sie
jederzeit verändern, indem Sie mit dem Mauszeiger auf die von Ihnen
gewünschte neue Farbe in den Buttons unter der Zeichenebene zeigen und die
zugehörige Maustaste drücken. Wollen Sie hingegen erfahren, welche Farbe
zur Zeit ausgewählt ist, drücken Sie die zugehörige Maustaste rechts außer-
halb der Zeichenebene und der entsprechende Farbbutton flackert auf.
Bei VGA- und EGA-Karten stehen Ihnen 16 verschiedene Farben zur Erstellung
des Sprites zur Verfügung.
Während Sie das Sprite erstellen, sehen Sie es als High-Res Zeichnung am
rechten Rand des Bildschirmes so, wie es später bei einer Verwendung in
einem Programm einmal aussehen wird.
Wenn Sie den Editor genau betrachtet haben, werden Sie noch zwei Buttons
sehen, die noch nicht erklärt worden sind. Mit dem <EXIT> Button verlassen
Sie den Eingabeebene mit der Maus. Wenn Sie hingegen den <CLR> Button mit
der linken Maustaste drücken, so wird die gesamte Ebene mit der aktuellen
Hintergrundfarbe geflutet. Da jede Farbe Hintergrundfarbe sein kann, ist
damit nicht nur das löschen der Ebene, sondern auch das Füllen mit einer
beliebigen Farbe möglich.

Wenn Sie Ihr Sprite fertiggestellt haben, können (und sollten) Sie es mit
der Taste <3> abspeichern. Danach können Sie es nochmals im Editor
verändern oder auch mit der Taste <5> konvertieren.
Nach dem Druck der Taste <5> erscheint ein komplettes Untermenü mit diversen
Möglichkeiten der Nachbearbeitung des Sprites.
Die ersten vier Optionen (<1>..<4>) geben Ihnen die Möglichkeit, das Sprite
komplett nach oben, unten, rechts oder links zu verschieben. Dabei kann es
jedoch immer nur soweit verschoben werden, wie sichergestellt ist, das keine
Teile des Sprites aus der Zeichnung verschwinden. Anders ausgedrückt können
immer nur Zeilen (Spalten) aus dem Sprite geschoben werden, die komplett
mit der aktuellen Hintergrundfarbe gefüllt sind.
Mit diesen 4 Optionen können Sie das Sprite nach Bedarf zentrieren. Manchmal
stellt sich jedoch bei der Sprite-Erstellung heraus, daß man eigentlich mehr
Platz benötigt, bzw. man stellt am Ende der Erstellung fest, daß das Sprite
kleiner als erwartet geworden ist. In diesen Fällen kann auch die Größe
des Sprites mit den Tasten <5>,<6> und <7> verändert werden. Dabei kann das
Sprite entweder auf Maximalgröße (32*32) oder auf Minimalgröße (8*8 oder
aber auch mehr) gebracht werden; es besteht jedoch auch die Möglichkeit,
die Größe des Sprites neu vorzugeben. In den beiden letzten Fällen bleibt
zu beachten, daß das Sprite nur soweit verkleinert wird, daß wiederum keine
Sprite-Daten verloren gehen. So kann es sein, daß ein Sprite nicht verklei-
nert werden kann, wenn es die Zeichenebene voll ausfüllt. Nach der Größen-
bearbeitung ist meist eine neue Zentrierung erforderlich, da das Sprite
immer in der linken oberen Ecke des neuen Zeichenfeldes abgebildet wird.

Mit all diesen Funktionen des Editors bezüglich Erstellung und Konvertierung
der Sprites sollten Ihnen gute Sprites in relativ geringer Zeit gelingen.
Achten Sie dabei bitte darauf, daß Sie die Sprites nicht größer als nötig
machen, denn je größer ein Sprite ist, desto größer wird der zeitliche
Aufwand bei der späteren Verschiebung des Sprites in Ihrem Programm!
Andererseits sollten Ihre Sprites möglichst einheitliche Formate haben, denn
dies erleichtert das Handling der Sprites später sehr.


Nach der Erstellung eines oder auch mehrerer Sprites können Sie diese in
ein erstes Turbo-Pascal-Programm einbinden. Dazu gibt es einen Ladebefehl
in der SPRITLIB-TPU. Zuvor muß jedoch eine weitere Besonderheit dieses
Programmpaketes erläutert werden.
Vielleicht haben Sie sich gewundert, warum bisher nie die Rede von
verschiedenen Grafik-Karten war. Tatsächlich können Sie ein Sprite gleich
für mehrere Grafik-Karten erstellen. Das liegt daran, das der Sprite-Editor
die Sprite-Daten in einem eigenen Format und nicht als Image speichert.
Dieses Verfahren bietet mehrere Vorteile:
1. Sie können ein Programm mit Sprites ausrüsten, ohne daß Sie sozusagen
   die "Sprite-Sources" mitliefern müssen.
2. Die Sprite-Sources können nachbearbeitet werden, die Sprite-Code-Files
   hingegen nicht.
3. Beim Einsatz der Sprite-Sources ist eine automatische Anpassung an die
   jeweils benutzte Grafik-Karte im Programmbetrieb möglich.
Also: Der Sprite-Editor legt grundsätzlich die Sprites in 1028-Byte-Dateien
ab. Diese Dateien sollten die Endung ".SPR" tragen und sind praktisch die
Source-Dateien der Sprites, deshalb können sie im Sprite-Editor auch erneut
bearbeitet werden. Eine Umwandlung in die kleineren Sprite-Code-Files, die
die Endung ".SCF" tragen sollten, kann auf zweierlei Weise erfolgen:
1. Die Laderoutine der SPRITLIB kann beide Sorten von Sprites einladen.
   Während ein Code-File sofort übernommen werden kann, muß ein Sources-File
   zunächst in ein Code-File umgewandelt werden. Dies dauert etwas länger,
   als das Laden des Code-Files. Außerdem wird das geladene Sprite für die
   Dauer der Umwandlung auf dem Bildschirm sichtbar. Der Vorteil liegt
   jedoch in der automatischen Anpassung an die Grafik-Karte, denn beim
   Laden von Code-Files muß diese unbedingt zu den geladenen Sprites passen!
2. Das Umwandlungs-Programm SPR_KONV.EXE konvertiert die Sources-Files des
   Sprite-Editors in sofort verwendbare Code-Files. Das Programm wird z.B.
   wie folgt gestartet: SPR_KONV DRACULA.SPR DRACULA.SCF <RETURN>
   Danach wandelt der Konverter die 1028-Byte-Datei DRACULA.SPR des Sprite-
   Editors in eine kleine Code-Datei mit dem Namen DRACULA.SCF um. Das
   Sprite wird dabei an die gerade vorhandene Grafik-Karte angepaßt.
   Verfügen Sie also über eine VGA-Karte, liegt das Sprite in einem Format
   für VGA-Karten vor, falls Sie hingegen eine HGC-Karte benutzen sollten,
   ist das ".SCF"-Sprite genau für HGC-Karten angepaßt.

Ob Sie in Ihren Programmen lieber die ".SPR"-Dateien oder die ".SCF"-Dateien
benutzen, bleibt eine Frage der Zielsetzung. Die Code-Dateien sind natürlich
kürzer und sicherer, aber von Ihnen muß für jede erlaubte Grafik-Karte ein
kompletter Satz vorhanden sein!


Die Benutzung der Library (SPRITLIB.TPU)

Sie binden die Library in Ihre TP-Programme durch eine "uses"-Anweisung
direkt nach dem Programm-Namen ein, also z.B.:

program meine_tollen_sprites;
uses graph,spritlib;

Dadurch sind Sie im Programm in der Lage, die folgenden Anweisungen im
Programmtext zu verwenden. Insgesamt stehen Ihnen 8 verschiedene Anweisungen
der Sprite-Library zur Verfügung. Im Anschluß folgen die Deklarationen
dieser Prozeduren und Funktionen. Bei der Eingabe der Anweisungen dürfen nur
die Variablen (Großbuchstaben!) mit Semikolon und Kommata angegeben werden.

1. Die Prozedur LOAD_SPRITE (FILENAME : String ; var NUMMER : Integer)

Mit dieser Anweisung wird das Sprite mit dem Pfad- und Dateinamen FILENAME
von der Diskette oder Harddisk in das Programm eingeladen. Falls die
Variable SPRITE_ERROR=0 ist, enthält Nummer nach dem Aufruf die Nummer
dieses Sprites, unter der es in Zukunft angesprochen werden kann.
Es können sowohl Sprite-Code-Files, wie auch Sprite-Source-Files geladen
werden, wobei letztere noch automatisch umgewandelt werden. In JEDEM Fall
muß der Rechner zum Zeitpunkt des Aufrufes dieser Funktion im GRAFIKMODUS
sein, sonst kann das Sprite nicht verarbeitet werden!

2. Die Prozedur UNLOAD_SPRITE (NUMMER : Integer)

Falls Sie an einer bestimmten Stelle des Programmes die Sprites wechseln
wollen und alle Plätze bereits belegt sind, können Sie sich mit dieser Pro-
zedur neuen Platz schaffen, indem Sie alte und nicht mehr benötigte Sprites
aus dem Speicher löschen. Die Prozedur entfernt das Sprite mit der Nummer
NUMMER aus dem Speicher. Danach kann diese Nummer von der Library für ein
neues Sprite vergeben werden. In der Grundversion stehen 12 Sprites mit
den Nummern 0 bis 11 zur Verfügung.

3. Die Prozedur SHOW_SPRITE (NUMMER,X,Y,E,M : Integer)

Mit dieser Prozedur stellen Sie ein geladenes Sprite zum ersten Mal dar.
Mit NUMMER geben sie die Nummer des Sprites an, welches Sie zeigen wollen.
X und Y beschreiben die X- und Y-Koordinaten einer bestimmten Ecke des
Sprites auf dem Grafik-Bildschirm. Mit E geben Sie die Ecke des Sprites an,
auf die sich die Koordinaten beziehen sollen:

    links oben  e=0         rechts oben  e=1

    links unten e=3         rechts unten e=2

Mit dieser Angabe können Sie sich leichter auf Sprites einstellen, die sich
auf etwas bewegen (e=2,e=3) oder an etwas hängen (e=0,e=1) und müssen nicht
immer die Sprite-Größe dabei bedenken. Der letzte Parameter M gibt schließ-
lich der Library Auskunft über die Methode mit der das Sprite mit dem
Bildschirminhalt unter dem Sprite verknüpft werden soll. Der Wert von M
darf zwischen 0 und 4 liegen. Was ein bestimmter Wert von M bewirkt, können
Sie in Ihrem Turbo-Pascal-Handbuch bei der Beschreibung der PutImage-
Prozedur nachlesen. Meistens verwendet man jedoch den Wert M=0.

4. Die Prozedur MOVE_SPRITE (NUMMER,X,Y : Integer)

Haben Sie ein Sprite mittels SHOW_SPRITE irgendwo auf dem Bildschirm
dargestellt, können Sie es mit dieser Prozedur von dort zu einer neuen
Stelle des Bildschirmes transportieren. Das Sprite wird an der alten Stelle
gelöscht und an der neuen Stelle wieder gezeichnet. Da sich dabei die
Parameter E und M meistens nicht ändern, braucht bei dieser Prozedur
nur die Nummer des angesprochenen Sprites mit seinen neuen Koordinaten
X und Y an die Prozedur übergeben werden. Wollen Sie E und M neu setzen,
benutzen Sie einfach HIDE_SPRITE und dann wieder SHOW_SPRITE.
Zur Priorität von Sprites ist zu sagen, daß stets das zuletzt bewegte Sprite
über den Sprites liegt, die länger als dieses Sprite nicht bewegt wurden.

5. Die Prozedur HIDE_SPRITE (NUMMER : Integer)

Wollen Sie ein Sprite nicht verschieben, sondern es erstmal oder endgültig
vom Bildschirm entfernen, rufen Sie diese Funktion auf. Sie brauchen nur
die Nummer des betroffenen Sprites anzugeben und es wird an seiner
augenblicklichen Position gelöscht. Das Sprite steht jedoch im Gegensatz
zur UNLOAD_SPRITE Prozedur weiterhin zur Verfügung.

6. Die Prozedur PRINT_SPRITE (NUMMER,X,Y,E,M : Integer)

Manchmal ist es wünschenswert, ein Sprite dauerhaft an einer Stelle abzu-
bilden, es sozusagen an einen Ort zu "stempeln". Durch den Aufruf dieser
Prozedur kann dieser Effekt erreicht werden. Die Parameter haben die
gleiche Bedeutung wie bei SHOW_SPRITE beschrieben.
Bei dieser Prozedur sind jedoch einige Besonderheiten gegeben:
Der Aufruf der PRINT_SPRITE Prozedur ändert weder den Zustand des Sprites,
noch seine Position. Dementsprechend muß des geprintete Sprite noch nicht
einmal sichtbar, aber natürlich zumindest geladen worden sein.
Der Hintergrund wird bei dieser Funktion nicht gesichert, was den Abdruck-
vorgang sehr beschleunigt. Man kann auf diese Art und Weise ein Sprite zum
schnellen Füllen einer Fläche mit einem Muster nutzen. Was jedoch unter der
Fläche an Bildschirminformationen vorlag, geht verloren.
Man könnte sagen, diese Prozedur überträgt eine Kopie des ausgewählten
Sprites dauerhaft an eine beliebige Bildschirmposition.

7. Die Prozedur SPRITE_POS (NUMMER : Integer ; var X,Y : Integer)

Die Prozedur liefert in den Variablen X und Y nach dem Aufruf die Position
des Sprites mit der Nummer NUMMER zurück. In X und Y findet sich die X-
bzw. die Y-Koordinate jener Ecke des Sprites, die beim Aufruf der Prozedur
SHOW_SPRITE im Parameter E angegeben worden ist. Die Funktion ist nur auf
sichtbare Sprites anwendbar.

8. Die Funktion SPRITE_KOL (NUMMER : Integer) : boolean

Oftmals ist es erforderlich zu wissen, ob ein bestimmtes Sprite zur Zeit
mit einem oder mehreren anderen Sprites kollidiert ist, ob also eine
Überlagerung stattfindet. Die Funktion SPRITE_KOL liefert Ihnen nun einen
booleschen Ausdruck dafür, den man etwa so verwenden kann:

IF sprite_kol(5) THEN mindestens_blechschaden ELSE tempo_erhöhen

Die Funktion liefert also den Wert TRUE für das Sprite mit der Nummer NUMMER,
wenn es mit einem anderen Sprite kollidiert ist, ansonsten den Wert FALSE.
Da es aber meistens von wesentlichem Interesse ist, mit welchem oder welchen
Sprites ein Sprite kollidiert ist, legt die Library eine Kollisionsliste
mit dem Namen KOL_LIST an. Dies ist ein boolesches Array, welches für jedes
Sprite einen Eintrag bereithält. Nach dem Aufruf von SPRITE_KOL (NUMMER)
kann für jedes definierte Sprite der Eintrag in dieser Liste abgefragt
werden:

IF sprite_kol(5)  THEN BEGIN    {Falls Sprite 5 eine Kollision hatte, ist}
   IF kol_list[0] THEN .....    {z.B. eine Kollision mit Sprite 0 erfolgt,}
   IF kol_list[1] THEN .....    {oder auch noch mit Sprite Nummer 1 usw.}
   ...
   END

Auf diese Weise können alle relevanten Kollisionspartner überprüft werden.
Eigenkollisionen eines Sprites mit sich selbst sind stets gegeben und werden,
da sie keine Informationen liefern, unterdrückt. Im obigen Beispiel ist also
KOL_LIST(5) stets FALSE, also unwahr.
Das Feld KOL_LIST braucht (und darf !) genau wie die Variable SPRITE_ERROR
nicht in Ihrem Programm definiert werden, da dies bereits die LIB besorgt.


Alle oben beschriebenen Prozeduren und Funktionen sind nur dann korrekt
und fehlerfrei ausgeführt worden, wenn nach ihrem Aufruf die Variable
SPRITE_ERROR=0 war. Enthält SPRITE_ERROR hingegen einen Wert kleiner als
Null, so hat das die folgenden Bedeutungen:

 SPRITE_ERROR     Bedeutung

       0          kein Fehler
      -1          Rechner befindet sich nicht im Grafikmodus
      -2          Sprite konnte nicht geladen werden (Datei-Lade-Fehler)
      -3          Sprite konnte nicht geladen werden (falsches Datei-Format)
      -4          Kein Platz für ein neues Sprite (kein Tabellenplatz)
      -5          Kein Platz für ein neues Sprite (kein Speicherplatz)
      -6          Die Nummer des Sprites ist in einem unzulässigen Bereich
      -7          Sprite ist undefiniert (Nummer wurde nicht vergeben)
      -8          Unerlaubte Koordinaten wurden für das Sprite angegeben
      -9          Zusatzangaben unzulässig (E und M bei SHOW_SPRITE)
     -10          Sprite ist zur Zeit hidden (unsichtbar)
     -11          Die geladene Sprite-Code-Datei paßt nicht zur Grafik-Karte

Ich hoffe, daß Sie mit den obigen Fehlernummern möglichst wenig konfrontiert
werden und wünsche Ihnen ein erfolgreiches Arbeiten mit SPRITLIB.TPU

Uwe Kuhring